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Pico-8 API Cheatsheet Version 0.1.10 
Introduction 

I've been working with the wonderful Pico-8 fantasy console for almost a week now and have to 
look into the API from time to time. Neko250 has created a fancy website which is licensed under 
the Creative Commons Attribution 4.0 International License. Unfortunately, I can only use the 
website for the Pico-8 API with JavaScript, but I have disabled it because of my Alligator Browser. I 
hereby port the API to a single subpage in my web project so that it can be read in my own browser 
(which I want to use more in the future). This will look less pretty here, but it will work better in a 
text browser (e.g. Lynx or W3M). 

Root 


Pico-8 Specs 

• - display: 128x128, fixed 16 colour palette 

• - input: 6 buttons 

• - cartridge size: 32k 

• - sound: 4 channel, 64 definable chip blerps 

• - code: lua, max 8192 tokens of code 

• - sprites: single bank of 128 8x8 sprites + 128 shared 

• - map: 128x32 8-bit cels + 128x32 shared 


General 


• fullscreen: / 

• quit: f4 J cmd 

• reload and run: 

• save: 

• mute/unmute: 

• show fps: 

• screenshot: / / 

• cart img: / / 

• start video: / s / 

• save video: / / 

• keyboard cursor: 

• navigate editors: ghtjait 

• cli completion: 




navigate lists: / 

navigate carts: ipB down B home B end B pageup BpagedownB 

launch cart: / ' 

- favourite cart: 


Sprite / Map Editor 

• undo: 

• copy (bbs support) 

• paste (bbs support): 

• pan: spaceMmmb 

• navigate sprites: 

• navigate colours: 

• navigate tabs: / 

• fullscreen: 

• zoom: 

• flip y<: 

• flip x: 

• rotate: 


i: 


draw tool 

• replace colour: 

• eyedropper: 


stamp tool 

• stamp w/transparency: 




• select sprites: 

Command Line Interface 

• assert(condition) 

• Cd .. hange to parent directory^® 

• cd [dirname] 

• dir() 

• exit() co-8 appflH 

• export(filename.html, [cartl.p8, cart2.p8 ... cartl5]) 

^^■carts ( .p8 format) 

• export(filename.png) export spritesheet|M 

• export(filename.wav) 

• export(filename%d.wav) 

• extcmd(cmd) 

^^nif; "video" = save gif^H 

• folderO 

• help() how summary of system commands 

- - expects png 

• infoQ 

• install_demos() tall demo p8 carts alongsid e pico-8 app^J 

bbs carts 

• keyconfigO 

• load("@clip") 

- - load works export^H 

• ls() 

• menuitem(index, [label, callback]) 

^Mlabel or callback removes the item|H 

• mkdir(dirname) 

• printh(str, [filename, overwrite]) 

• rebOOt() reboot pico8| 

• resumeO 

• run() 

• save("@clip") copy cart to clipboard, bbs support^® 

• save(filename) 

• shutdown() 

• sploreO explore cartridges 

• Stat(x) -- read some execution values, read below^H 

• time() 

• type(v) 


• skip across words: eft Jc 

• select: 

• select word: 

• cut: 

• copy: 

• paste: 

• undo: 

• redo: 

• indent: 

• unindent: 

• duplicate line: 

• search: 

• repeat search: 

• navigate functions! ait + upWait 

• start / end of code: / 

• button glyphs: 

• icons: t + qwetyipasfghj kzcvbnm 

• glyph mode: 

SFX / Music Editor 



play / pause: 
copy: 
paste: 

set all notes: 
modify speed: / 

^^^^^^■homelend ^ pag eup Jpagedown^mou 

navigate patterns: / 
snap to Cm pentatonic: 





• speed x4: 

• release loop: 

• delete: 

effects 

• 0 :: none 

• 1 :: slide 

• 2 :: vibrato 

• 3 :: drop (drum kick!) 

• 4 :: fade in 

• 5 :: fade out 

• 6 :: fast arpeggio (4 notes) 

• 7 :: slow arpeggio (4 notes) 

Pico-8 Manpage 

• pico-8 [switches] [filename.p8] 

• -run 

set the window or screen width and adjust scale to fit if not specifiedl 
set the window or screen height and adjust scale to fit if not specifiei 

• -windowed b windowed mode off 

• -sound n sound volume [0..256]^H 

• -music n ;ound volume [0..256]M 

• -joystick n 

• -pixel_perfect b t filter for screen stretching off (0] 

• -draw_rect x,y,w,h 

• -splore 

• -home path customise home directory^® 

set desktop path for screenshots and gifs^H 

• -screensh0t_scaie n # size of each screenshot 

• -gif_scale n 

set the maximum gif length in seconds; n in [1..120]^| 

• -gui_theme n # set the code edito 

• -timeout n 

• -frameless to# set borderless window off (0) 

• -show_fps b t fps display off (0) or on (1)H 

Audio 



• music([n, [fadejen, [channel mask]]]) 

• sfx(n, [channel, [offset]]) 

Cart Data 

- - open cart data named id (once per execution! )^H 

• dget(idx) - get number at index^B 

• dset(idx, val) 


Coroutines 

Coroutines 

• cocreate(f) a coroutine that executes f^H 

• coresume(c) j - - resume corout 

returns true if c is still executing, false otherwise^! 

• yield() 

Graphics 







□ 15 3 
H 5 

EE 


No. 

Hex-Code 

RGB 

Name 

0 

#000000 

(0, 0, 0) 

Black 

1 

#000000 

(29, 43, 83) 

Dark-Blue 

2 

#7E2553 

(126, 37, 83) 

Dark-Purple 

3 

#008751 

(0, 135, 81) 

Dark-Green 

4 

#AB5236 

(171, 82, 54) 

Brown 

5 

#5F574F 

(95, 87, 79) 

Dark-Gray 

6 

#C2C3C7 

(194, 195, 199) 

Light-Gray 

7 

#FFF1E8 

(255, 241, 232) 

White 

8 

#FF004D 

(255, 0, 77) 

Red 

9 

#FFA300 

(255, 163, 0) 

Orange 

10 

#FFEC27 

(255, 236, 39) 

Yellow 

11 

#00E436 

(0, 228, 54) 

Green 

12 

#29ADFF 

(41, 173, 255) 

Blue 

13 

#83769C 

(131, 118, 156) 

Indigo 

14 

#FF77A8 

(255, 119, 168) 

Pink 

15 

#FFCCAA 

(255, 204, 170) 

Peach 


Source: Roman Zolotarev's PICO-8 palette reference 

• camera([x, y]) 

• circ(x, y, r, [col]) 

• circfill(x, y, r, [col]) 

• clip([x, y, w, h]) 

• cls([col]) 

• color(col) 

• cursor(x, y) 

• fget(n, [f])| get i of 

• flipO 

• fset(n, [f], v) 

• Iine(x0, yO, xl, yl, [colli draw tin 

- switch colour 0 to colour 1; p = 0 = draw palette; p = 1 = screen palette 

• palt(COl, t) colour to t (bool)^H 

• pget(x, y) et pixel colour^^^^^^H 

• print(str, [x, y, [col]]) 

• pset(x, y, [col]) 

• rect(x0, yO, Xl, yl, [col]) draw rectangle® 

• rectfill(xO, yO, xl, yl, [col]) 

• sget(x, y) 

• spr(n, x, y, [w, h], [flipx], [flipy]) 

• sset(x, y, [col]) 

• sspr(sx, sy, sw, sh, dx, dy, [dw, dh], [flip x], [flip y]) 

• fillp(mask) 

fillpO Mask 


|32768|16384| 8192| 4096| 

I..I.I 

j 2048| 1024| 512 j 256 | 

I.I.I.I.I 

j 128 j 64 j 32 j 16 j 








Input 

Input Manipulation 



PHUSE: P f EnTER 

PLRUER 1: OOO Z,K / C,U S D,n 

PLHUER 2: FED, LSHIFT, H / THE, t 


• btn([i, [p]]) 

-- only true when the button was not pressed the last frame; repeats every 4 frame; 
^Efter button held for 15 frames^® 


Map 

Map Manipulation 

• map(cel_x, cel_y, sx, sy, cel_w, cel_h, [layer] 

• mapdraw(cel_x, cel_y, s Xi SV . cel_w, cel_h, [layer]) 

• mget(x, y) - get map valueH 

• mset(x, y, v) 

Math 

Math Functions 

• -32768.0 .. 32767.99 

absolute value 

• atan2(dx, dy) 

• band(x, y) - bitwise conjunctionBB 

• bnot(x) 

• bor(x, y) 

• bxor(x, y) 

• cos(x) 

• flr(x) 

not a function per se, but will work as ceil(x)^B 

• max(x, y) x/y maximum 

• mid(x, y, z) 

• min(x, y) 

• rnd(x) andom; 0 <= n < ; 

returns argument sign: -1 or 1; sgn(0) = l^B 

• Shl(x, y) shift left^^B 

• shr(x, y) 

• sin(x) V [ 0. . 1 ] ; 

• sqrt(x) 

• srand(x) 

Operators 

• a + b 

• a - b 

• a * b 

• a / b 

• a % b 

• a ~ b 

• a += b 

• a -= b 

• a *= b 








• a /= b 

• a %= b 

• a ~= bl - pow to | 

• a == b jmpare equals^® 

• a ~= b pare not equals^H 

• a != b 

• a > b 

• a < b 

• a >= b 

• a <= b :are less than or equals^! 

• not a -- boolean negatior 

• a and b 

• a or b 

• (a) operation delimiters ■■ 

Flow Control 


::label:: -- label 
goto label -- jump 

if (<condition>) -- inline if 

if <condition> then 
-- if block 

elseif <condition> then 
-- elseif block 
else 

-- else block 
end 

while <condition> do 
-- while block 
end 

repeat 

-- repeat block 
until <condition> 

for <var> = <first>, <last>, <step> do 
-- for block 
end 

for <var> in all(<table>) do 
-- for block 
end 

for <key>, <value> in pairs(<table>) do 
-- for block 
end 


Memory 


Memory Manipulation 

• cstore(dest_addr, src_addr, len, [filename]) 

^^Kiforks export]^^ft#y^^^K£fi£iiBJU ? 

• memcpy(dest_addr, src_addr, len) Tbytes! 

• memset(dest_addr, val, len) 

• peek(addr) 

• poke(addr, val) 

• reload(dest_addr, src addr, len, [filename]) 

^^Kiforks with multi-cart exportl^H 


Memory Types 

1. base ram (32kB) 

2. cart rom 

3. lua ram (1MB) 

RAM Layout 

• 0x1000 - gfx2/map2 (shared) 

• 0x2000 - map 

• 0x3000 - gfx props 

• 0x3100 - song 

• 0x3200 - sfx 

• 0x4300 - user data 

• 0x5e00 - persistent cart data (256 bytes) 

• 0x5f00 - draw state 






1 0x5f40 - hardware state 
' 0x5f80 - gpio pins (128 bytes) 
0x6000 - screen (8k) 


Devkit Input Mode 


read keyboard had input (bool); repeats every A 
read keyboard character^® 

read x coord 

read y coord^H 

read button bitmask; 1 = primary, 2 = secondar> 


• key held for 15 frames I 


Extra Graphics Mode 

• poke(0x5f2c, 0) 

• poke(0x5f2c, 1) 

• poke(0x5f2c, 2) 

• poke(0x5f2c, 3) 

• poke(0x5f2c, 4) 

• poke(0x5f2c, 5) 

• poke(0x5f2c, 6) 

• poke(0x5f2c, 7) 


standard, 128x128^1 
horizontal stretch, 64x1 28^ 
vertical stretch, 128x64^J 
zoomed, 64x64|H 


r top half^^l 
r top-left quart 


Raspberry Pi / Pocketchip GPIO 

• run pico-8 as root ; ‘sudo pico-8") 

• poke(0x5f80, value) 

• peek(0x5f81) 

get value from gpio 


called once per visible frame! 
_init() called once on 

_update() 

_update60() lied once per update at 


memory usage in [0..1024]^| 
stat(l) -- cpu usage; 1.0 == 100% cpuat30fps^M 
clipboard; after user pressed ctrl-v^H 

index of playing sfx on channels [0..3] 
note number (0..31) on channels [0..3]J 

- - keyboard key hit; see "peek / poke" tab| 

- - keyboard character; see "peek / poke" tabH 

mouse x coord; see "peek / poke" tabH 
mouse y coord; see "peek / poke" tab^l 
mouse button bitmask; see "peek / poke" ta 


piC08_gpi0[] ead and write gp: 

1 pico8_buttons[] 


Private Functions (use carefully) 

• _get_frames_skipped() - used aut 

• _get_menu_item_selected(n) returns true or false if 
^H[1..5]; used automatically by mainloopO^H 

• _mainloop() true" 

• _pausemenu[n].callback() 

^^Bautomatically by mainloop () ■■ 

• _set_mainloop_exists(n) 

• _update_buttons() -- used automatically by mainloop () ■ 

• holdframeO 


Strings 








BE 

O 

R1 : 0 

RH 

O 

B3 :0 

BE 

o 

R1:Q 




BD 

■ 

B1: BH 

BE 

w 

B3 : O 

BH 


BB: * 

Bb 

* 

B1 : ¥ 

BB 

* 

BR: * 

BH 

* 

BE : O 

BC 

s 

BB: J- 

BE 

o 

BF: + 

RD 


R1:0 

RE 
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R3 : I 

HR 

o 

RB: -v 

Rb 

w 

RT: O 

RB 

= 

RR : Mil 





• #s -- string length 

• "three " .. 4 

• sub(str, from, [to]) 

• tostr(val, [hex]) 

cast parseable str to number; nil if str isn't a number; "OxAF" format for hex! 

• "123.45" + 0 

special characters 


print("l:\x8b r:\x91 u:\x94 d:\x83 o:\x8e x:\x97") 


Tables 


Table Manipulation 

• add(t, v) 

in ’for v in all(t) 1 loops® 
returns number of elements in the table! 

• del(t, v) delete first instance of v in t^H 

• foreach(t, f) 

^~sed in 'for k,v in pairs(t)' loopsH 

Metatables 

• mt = {} 

• setmetatable(t, mt) 

Metatables :: Special Keys 


-- object oriented programming; invoked as 't:foo()' / 1 1:bar() 1 
fun = {} 

function fun.foo(t) dosomething() end 
function fun.bar(t) dosomethingmoreO end 
mt._index = fun 

-- property assignment; invoked when calling 1 t[k] = v' 
function mt._newindex(t, k, v) rawset(t, k, v) end 

-- weak references; keys and / or values 
mt._mode = "k" or "v" or "kv" 

-- treat a table like a function; invoked when calling ‘t() 1 
function mt._call(t) dosomething() end 

-- hide metatable; returned by 'getmetatable(t)' 

publicmt = {} 

mt._metatable = publicmt 

-- string casting; returned by 'tostring(t)' 
function mt._tostring(t) return tostring(t) end 

-- table length; returned by '#t' 
function mt._len(t) return #t end 


Metatables :: Mathematic Operators 


-- unary minus; returned by 1 -1' 
function mt._unm(t) return -t end 

-- addition; returned by 'a + b' 
function mt._add(a, b) return a + b end 








b end 


-- subtraction; returned by 'a - b 
function mt._sub(a, b) return a - 

-- multiplication; returned by 'a * b' 
function mt._mul(a, b) return a * b end 

-- division; returned by 'a / b' 
function mt._div(a, b) return a / b end 

-- modulo; returned by 1 a % b 1 
function mt._mod(a, b) return a % b end 

-- involution; returned by 'a ~ b' 
function mt._pow(a, b) return a ~ b end 

-- concatenation; returned by 'a .. b' 
function mt._concat(a, b) return a .. b end 


Metatables :: Comparison Operators 


-- check for equality; returned by 'a == b' 
function mt. eq(a, b) return a == b end 

-- check for less-than; returned by 'a < b' 
function mt._lt(a, b) return a < b end 

-- check for less-than-or-equal; returned by 'a <= b' 
function mt._le(a, b) return a <= b end 




